Overview
This document provides details on the RHQ control script, rhqctl. The purpose of the control script is to provide basic lifecycle management of RHQ services installed on a server machine. Within the context of this document an RHQ service refers specifically to one of the RHQ Server, RHQ Agent, or RHQ Storage Node.
rhqctl is for managing the RHQ services necessary for running the RHQ Server. The RHQ Server needs at least one RHQ Storage Node (running locally or remotely) for persisting data. In order to be managed, RHQ Storage Node itself needs an RHQ Agent. Therefore, rhqctl can be used to manage the lifecycle of those components (RHQ Server, RHQ Storage Node and RHQ Agent).
Do not use rhqctl on your agent machines. On your machines where you only need an RHQ Agent, you only need to install and upgrade the agent using the normal agent install/upgrade mechanisms and run the agent using the normal start/stop mechanisms. rhqctl is only for use on your server machines where you have RHQ Servers and/or RHQ Storage Nodes (and their associated RHQ Agents) installed.
Basic lifecycle management includes,
-
Installing
-
Upgrading from older versions
-
Starting
-
Stopping
-
Checking status (to see whether or not services are running)
-
Starting in console mode (i.e., in the foreground)
A primary objective of the control script is usability. As such rhqctl has only a handful of commands and a limited number of options. To the greatest extent possible, the script should figure out what it needs to do without additional user input or configuration. For example, if you invoke the script with the "start" command and no options, it will determine what services are installed on the machine and for each service that is not running, the script will start the service.
Commands
The section gives an overview of basic usage and the commands that rhqctl supports. To see a list of supported commands along with basic help information run the script without any arguments.
$ ./rhqctl
15:39:00,629 INFO [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl <cmd> [options]
where <cmd> is one of:
console <[options]> Starts an RHQ service in the foreground. Only --server or --storage is supported.
To start the agent in the foreground, use the <RHQ_AGENT_HOME>/bin/rhq-agent.(sh|bat)
script.
install <[options]> Installs RHQ services.
start <[options]> Starts RHQ services.
status <[options]> Check status of RHQ services
stop <[options]> Stops RHQ services
upgrade <[options]> Upgrades RHQ services from an earlier installed version
remove <[options]> Windows only. Removes RHQ Windows services
* For help on a specific command: rhqctl <cmd> --help
* Limit commands to a single component with one of: --storage, --server,
--agent
If you run the RHQ Server on a UNIX-based operating system, you may want to use the bash autocompletion script for rhqctl. To make it work, all you have to do is to copy the rhqctl-completion.sh script to your /etc/bash_completion.d/ directory. Everytime you write rhqctl in the terminal and press the <TAB> key, you will get an advice what can follow in given context.
install
$ ./rhqctl install --help
15:40:50,087 INFO [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl install [options]
Installs RHQ services.
--agent Install RHQ agent. The install directory will be [/home/bob/rhq-agent]
specify --storage to install one.
--start If specified then immediately start the services after installation. Note that
services may be started and shut down as part of the installation process, but
will not be started or left running by default.
--agent-config <arg> An alternate XML file to use in place of the default agent-configuration.xml
--agent-preference <arg> An agent preference setting (whose argument is in the form 'name=value') to be
set in the agent. More than one of these is allowed.
--server Install RHQ server. If you have not yet installed an RHQ storage node somewhere
in your network, you must specify --storage to install one.
The rhq-server.properties file should be updated as desired, prior to install.
--storage Install RHQ storage node. The install directory will be [/home/bob/rhq-storage].
The rhq-storage.properties file should be updated as desired,
prior to install. Note that this option implies --agent which means an agent will
also be installed, if one is not yet installed.
--storage-data-root-dir <arg> The root directory under which all storage data directories will be placed.
When no options are specified rhqctl install installs all previously uninstalled services - the storage node followed by the server and then the agent. Installation includes laying the bits down on disk, configuring the service, and then starting the service. When the install command finishes (and no options are supplied), the storage node, the server, and the agent should all be up and running.
--agent
rhqctl install --agent will install the agent. If the agent is already installed, a warning message will be displayed and agent installation will be skipped.
--server
rhqctl install --server will install the server. If the server is already installed, a warning message will be displayed and server installation will be skipped.
--storage
rhqctl install --storage will install the storage node. If the storage node is already installed, a warning message will be displayed and storage node installed will be skipped.
Executing rhqctl install --storage results in both the storage node and agent being installed even though the agent option is not specified. This is because RHQ requires an agent to be installed along side a storage node so that it can be fully managed.
--agent-config
Specifies an alternative XML file to use in place of the default agent-configuration.xml. You can use this if you want to preconfigure your agent with your own custom settings.
If a relative path is specified with the {{agent-config} option, it will be resolved relative to <rhq-server-dir>.
Values are treated like Java strings. So:
-
Use forward slashes where possible, especially in directory or file paths (including Windows!). For example: /var/lib or C:/my/folder.
-
If you need an explicit backslash, escape it using a double-backslash.
--storage-data-root-dir
By default, the RHQ Storage Node will persist its data on the filesystem under <rhq-home>/rhq-data. <rhq-home> is the parent of the <rhq-install-dir>. For example if you unzip the distribution as /opt/rhq/rhq-server-<version>, then /opt/rhq is the home directory, and the storage node will persist data under /opt/rhq/rhq-data. If you do not want data stored in that directory then specify a different root directory that the RHQ Storage Node will have read-write access to. It should not be placed under the server distribution for upgrade purposes.
Examples
This is the basic install command which will install all components (an RHQ Server, RHQ Storage Node, and RHQ Agent):
To install only the server, you would run the following (which assumes you already have a RHQ Storage Node installed and configured elsewhere):
$ rhqctl install --server
upgrade
$ ./rhqctl upgrade --help
12:08:54,374 INFO [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl upgrade [options]
Upgrades RHQ services from an earlier installed version
--start If specified then immediately start the services after upgrade. Note that
services may be started and shut down as part of the upgrade process, but
will not be started or left running by default.
--from-agent-dir <arg> Full path to install directory of the RHQ Agent to be upgraded. Required
only if an existing agent exists and is not installed in the default
location: <from-server-dir>/../rhq-agent
--from-server-dir <arg> Full path to install directory of the RHQ Server to be upgraded. Required.
--run-data-migrator <arg> This option is valid only when upgrading from older systems that did not have
storage nodes. The existing metric data needs to migrate to the metric storage.
The upgrade process can trigger this or give you an estimate on the duration.
If you want to have fine control over the process, please run the migrator on
the command line. Options are none (do nothing), estimate (estimate the
migration time only), print-command (print the command line for a manual run),
do-it (run the migration)
--storage-data-root-dir <arg> This option is valid only when upgrading from older systems that did not have
storage nodes. Use this option to specify a non-default base directory for the
data directories created by the storage node. For example, if the default
directory is not writable for the current user (/var/lib on Linux) or if you
simply prefer a different location.
--use-remote-storage-node <arg> By default a server is co-located with a storage node. However, if this option
is set to true, no local storage node will be upgraded and it is assumed a
remote storage node is configured in rhq-server.properties.
--from-server-dir
This points to the location of the old server installation - this is the server you want to upgrade.
--from-agent-dir
If you installed your agent in a place other than the directory "rhq-agent" which is a peer directory to the --from-server-dir, then you must specify --from-agent-dir in order to upgrade the old agent. If you have no agent to upgrade, this need not be specified.
Examples
Upgrade the server. If this was an older server that did not have a storage node, an RHQ Storage Node and RHQ Agent will be installed when upgrading that server.
$ ./rhqctl upgrade --from-server-dir /opt/rhq/rhq-server
Upgrade the server and the agent. If this was an older server that did not have a storage node, an RHQ Storage Node will be installed when upgrading that server.
$ ./rhqctl upgrade --from-server-dir /opt/rhq/rhq-server --from-agent-dir /home/rhq/rhq-agent
Upgrade the server and put the storage node's data directories under the given root directory:
$ ./rhqctl upgrade --from-server-dir /opt/rhq/rhq-server --storage-data-root-dir /home/rhq/storage-data
Upgrade the server but do not install or upgrade any storage node. This requires that you have already configured your rhq-server.properties to point to a remote storage node cluster. Without a storage node (either remote or local), the server will fail to operate correctly.
$ ./rhqctl upgrade --from-server-dir /opt/rhq/rhq-server --use-remote-storage-node true
start
$ ./rhqctl start --help
11:56:00,344 INFO [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl start [options]
Starts RHQ services.
--agent Start RHQ agent
--server Start RHQ server
--storage Start RHQ storage node
When no options are specified rhqctl will start all installed services that are not already running.
--storage
Start the storage node. If the storage node is already running, rhqctl will log a message to indicate that it is already running. A warning is logged if the storage node is not installed.
--server
Start the server. If the server is already running, rhqctl will log a message to indicate that it is already running. A warning is logged if the server is not installed.
--agent
Start the agent. If the agent is already running, rhqctl will log a message to indicate that it is already running. A warning is logged if the agent is not installed.
Examples
Start only the storage node.
$ ./rhqctl start --storage
Start the storage node and the server.
$ ./rhqctl.sh start --storage --server
Start only the agent.
stop
$ ./rhqctl stop --help
11:58:02,183 INFO [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl stop [options]
Stops RHQ services
--agent Stop RHQ agent
--server Stop RHQ server
--storage Stop RHQ storage node
When no options are specified, rhqctl will stop all installed services that are running.
--storage
Stop the storage node. Log a warning message if the storage node is not installed.
--server
Stop the server. Log a warning message if the server is not installed.
--agent
Stop the agent. Log a warning message if the agent is not installed.
Examples
Stops only the storage node. If there is a server running, you must have other RHQ Storage Nodes running that the server can access; otherwise, errors will occur when the server attempts to persist data to storage.
$ ./rhqctl stop --storage
Stop the storage node and the server.
$ ./rhqctl stop --storage --server
Stop only the agent.
status
$ ./rhqctl status --help
12:00:06,518 INFO [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl status [options]
Check status of RHQ services
--agent Check status of RHQ agent
--server Check status of RHQ server
--storage Check status of RHQ storage node
When no options are are specified, rhqctl will report the status of all installed services, indicating whether or not they are running.
--storage
Report the status of the storage node. Log a warning if the storage node is not installed.
--server
Report the status of the server. Log a warning if the server is not installed.
--agent
Report the status of the agent. Log a warning if the agent is not installed.
Examples
Report the status of the storage node.
$ ./rhqctl status --storage
Report the status of the storage node and the server.
$ ./rhqctl status --storage --server
Report the status of the agent.
$ ./rhqctl status --agent
console
$ ./rhqctl console --help
12:00:55,501 INFO [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl console [options]
Starts an RHQ service in the foreground. Only --server or --storage is
supported. To start the agent in the foreground, use the
<RHQ_AGENT_HOME>/bin/rhq-agent.(sh|bat) script.
--server Start the RHQ server in the foreground
--storage Start the RHQ storage node in the foreground
The console command is different from the start command in that it requires you to specify one and only one component to start. When no options are specified or when multiple options are specified, rhqctl just displays the usage message shown above.
--storage
Start the storage node in the foreground. Log a warning if the storage node is not installed or if it is already running.
--server
Start the server in the foreground. Log a warning if the server is not installed or if it is already running.
--agent
The --agent option is not yet fully implemented and therefore not a valid option. See BZ 970953